The TextBox Control

The TextBox is a container (orange box above) which has many practical uses in an application. Its most commonly used to prompt the user to enter data by:

  • clicking the search button inside the textbox and selecting a value from a table
  • entering data values from a scanned barcode
  • entering data via a soft or physical keyboard

Additional Features

The TextBox also had graphical properties that go beyond using the TextBox as a prompt for data entry purposes. Here are a few examples:

  • AllowFocus = True enables the action options that are also set to True. These actions are: AllowBackup - moves the promp to the prior control; AutoSelectText - automatically select text; EraseOnBackup - deletes the text entered into the prompt; FocusOnClick - sets focus on the prompt when its clicked on by the user.
  • The AllowFocus > OnEnterproperty sets specific actions once the control has focus. These are: Advance to the next next highest promptID); ExitForm, HoldForm, NextPage, ResetForm and Submit.
  • The AllowFocus > ShowError property if set to True will automatically displays an error form using the theme set for the error condition. For example, if a user enters invalid data or didn't make any entries in a TextBox that fails the validation for that entry, then an error message would display. If an input was required and the user didn't enter anything, an error message would display. The user has to either backup or clear the error condition to continue.
  • If the Required property is set to True, the prompt will not progress until data is entered into TextBox.
  • Assign other icons and actions to an event beside Search inside the TextBox via the Button property group. On some platforms the Event accesses the device's system operation like scanning/camera.
  • Set pre-formatted or customized text via the Defaults property so repetitive data values such as the location of a warehouse isn't re-enter for every transaction.
  • Link Error Messages to customized text via the ErrorMessages - TextId property for easier error handling in your script. Note that the appearance of the error message if the user's input is rejected can be set under AllowFocus > ShowError.
  • Launches a virtual keyboard (also called a soft keyboard or soft input panel).
  • Link a data a user entered to a Label's caption via the LinkLabel property.
  • Instead of having a Label control, use the TextHint property to describe what to enter inside the textbox itself.
  • Automate the TextBox to automatically accommodate the fontsize when IntegralHeight is set to True.
  • Automatic text wrapping. At runtime, if a user enters text in a textbox, it will automatically wrap. (The developer does not need to set the TextOptions property to the MultiLine.)

For more details on the properties used here, see the Graphical Control Properties topic.

To enable Search in the TextBox control

1. Make sure the AllowFocus is set to True and Visible is set to True.

2. Set Buttons > Action to Search.

3. Set Buttons > Image to Search. (This will display a magnifying glass icon.)

4. Set Buttons > Visible to True. (So the image will display.)

5. Set the Alignment location for the Search icon (left or right side of the textbox).

6. Set Events > OnSearch to True. This will open the Script designer and add the OnSearch procedure.

7. Enter your script for the Search text.

To enable Scan in the TextBox control

1. Make sure the AllowFocus is set to True and Visible is set to True.

2. Set Buttons > Action to Event.

3. Set Buttons > Image to Camera. (This will display a Camera icon.)

4. Set Buttons > Visible to True. (So the image will display.)

5. Set the Alignment location for the Camera icon (left or right side of the textbox).
Note: If you do not see the Events property in Control Properties, click on the Options icon and select Show Scripting Events.

6. Set Events property > OnScan to True. This will open the Script designer and add the OnScan procedure.

7. Enter your script for the OnScan procedure.